IPython/Notebook essentials

A notebook is a document formed by cells; each cell can contain Python code to execute (cell type Code) or documentation (cell type Markdown, also including Heading markdown). There are also other, more exotic, cell types.

A cell is executed by pressing Ctrl-RETURN on it (or Shift-RETURN to execute and advance to the next cell). The outcome of the computation (typically the result of the last statement) is output to the notebook (unless the statement is ended by a semicolon). Explicit output is also possible, using print statements.

The top menu in a notebook has a Help entry with generic information on the notebook interface, as well as links to the documentation for IPython and for relevant Python libraries. First-time users should start by clicking on the User interface Tour in that Help menu.

"Code" notebook cells execute IPython code. IPython is standard Python, with facilities added for interactive execution. It also provides online help at any moment. To launch it, use the question mark. Try it now by executing the following cell:

It is also possible to obtain help for specific Python methods, classes or functions. For instance, execute the following cell:

There is also contextual help (tooltips) and autocompletion:

• <shift-TAB> brings in Python documentation for the object just before the cursor, by opening a help window (pressing <shift-TAB> twice will show an enlarged)
• TAB performs automatic completion (or shows a list for selection) for methods, variables and arguments

Again, for people new to notebooks, please use now the Help/User interface Tour menu entry to get a feeling on the capabilities of the user interface.

Magics

IPython also provides magics, which are non-Python commands that start with a % (line magic) or a %% (cell magic) and perform some special processing, like configuring some notebook feature, or running code in other languages.

The %lsmagic command provides a list of all defined magics. Execute the following cell:

Extensions

A notebook deployment may contain extensions, which add additional functionality to the standard base software.

This deployment comes with four such extensions preinstalled:

• a ToC (Table of Contents) extension, which can display all the headings in a notebook as a floating menu. This comes especially handy to navigate long notebooks. The extension adds a small ToC icon to the right of the toolbar. Click on it to activate/deactivate the ToC for the current notebook.
• A "Toggle headers" button added to the right side of the menubar. This switches on/off at the same time both the heading and the toolbar, maximizing space for the notebook.
• A "Search toolbar" button, to perform interactive search & replace across the whole document (note there is also a "Find and Replace" menu option under "Edit", with slightly different functionality.
• The Python markdown extension, which enables evaluating Python code inside Markdown cells.

These extensions have also keyboard shortcuts.

Memory management

Important: Since every notebook started launches a kernel, it consumes a sizable amount of memory. This is specially significant for the kernels that launch a Spark driver process.

Therefore there is a not-too-high limit on the number of notebooks that can be running at the same time. If that limit is exceeded, an error will be generated. There are two solutions:

1. Close some of the open notebooks (shutdown their kernels). This can be done in the notebook browser:
   • by using the "Running" tab in the Notebook explorer, which shows all currently running kernels.
   • on each notebook window, by selecting "File" -> "Close and halt", which will terminate the kernel and close the notebook window. Note that merely closing the window does not terminate the kernel: it keeps running in the background (and opening the Notebook again can continue intraaction).
2. Increase the RAM assigned to the virtual machine running the notebooks. This can be adjusted in the Vagrantfile and is 2 GB by default